<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>LDAP Authentication - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.auth.adapter.ldap.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.auth.adapter.ldap.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.auth.adapter.http.html">HTTP Authentication Adapter</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.auth.html">Zend_Auth</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.auth.adapter.openid.html">Open ID Authentication</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.auth.adapter.ldap" class="section"><div class="info"><h1 class="title">LDAP Authentication</h1></div>
    

    <div class="section" id="zend.auth.adapter.ldap.introduction"><div class="info"><h1 class="title">Introduction</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Auth_Adapter_Ldap</span> supports web application authentication
            with <acronym class="acronym">LDAP</acronym> services. Its features include username and domain name
            canonicalization, multi-domain authentication, and failover capabilities. It has been
            tested to work with
            <a href="http://www.microsoft.com/windowsserver2003/technologies/directory/activedirectory/" class="link external">&raquo; Microsoft
                Active Directory</a> and <a href="http://www.openldap.org/" class="link external">&raquo; OpenLDAP</a>,
            but it should also work with other <acronym class="acronym">LDAP</acronym> service providers.
        </p>

        <p class="para">
            This documentation includes a guide on using
            <span class="classname">Zend_Auth_Adapter_Ldap</span>, an exploration of its
            <acronym class="acronym">API</acronym>, an outline of the various available options, diagnostic
            information for troubleshooting authentication problems, and example options for both
            Active Directory and OpenLDAP servers.
        </p>
    </div>

    <div class="section" id="zend.auth.adapter.ldap.usage"><div class="info"><h1 class="title">Usage</h1></div>
        

        <p class="para">
            To incorporate <span class="classname">Zend_Auth_Adapter_Ldap</span> authentication into your
            application quickly, even if you&#039;re not using <span class="classname">Zend_Controller</span>,
            the meat of your code should look something like the following:
        </p>

        <pre class="programlisting brush: php">
$username = $this-&gt;_request-&gt;getParam(&#039;username&#039;);
$password = $this-&gt;_request-&gt;getParam(&#039;password&#039;);

$auth = Zend_Auth::getInstance();

$config = new Zend_Config_Ini(&#039;../application/config/config.ini&#039;,
                              &#039;production&#039;);
$log_path = $config-&gt;ldap-&gt;log_path;
$options = $config-&gt;ldap-&gt;toArray();
unset($options[&#039;log_path&#039;]);

$adapter = new Zend_Auth_Adapter_Ldap($options, $username,
                                      $password);

$result = $auth-&gt;authenticate($adapter);

if ($log_path) {
    $messages = $result-&gt;getMessages();

    $logger = new Zend_Log();
    $logger-&gt;addWriter(new Zend_Log_Writer_Stream($log_path));
    $filter = new Zend_Log_Filter_Priority(Zend_Log::DEBUG);
    $logger-&gt;addFilter($filter);

    foreach ($messages as $i =&gt; $message) {
        if ($i-- &gt; 1) { // $messages[2] and up are log messages
            $message = str_replace(&quot;\n&quot;, &quot;\n  &quot;, $message);
            $logger-&gt;log(&quot;Ldap: $i: $message&quot;, Zend_Log::DEBUG);
        }
    }
}
</pre>


        <p class="para">
            Of course, the logging code is optional, but it is highly recommended that you use a
            logger. <span class="classname">Zend_Auth_Adapter_Ldap</span> will record just about every bit
            of information anyone could want in <var class="varname">$messages</var> (more below), which is
            a nice feature in itself for something that has a history of being notoriously difficult
            to debug.
        </p>

        <p class="para">
            The <span class="classname">Zend_Config_Ini</span> code is used above to load the adapter
            options. It is also optional. A regular array would work equally well. The following is
            an example <var class="filename">application/config/config.ini</var> file that has options for
            two separate servers. With multiple sets of server options the adapter will try each, in
            order, until the credentials are successfully authenticated. The names of the servers
            (e.g., &#039;server1&#039; and &#039;server2&#039;) are largely arbitrary. For details regarding the options
            array, see the <em class="emphasis">Server Options</em> section below. Note that
            <span class="classname">Zend_Config_Ini</span> requires that any values with &quot;equals&quot; characters
            (<em class="emphasis">=</em>) will need to be quoted (like the DNs shown below).
        </p>

        <pre class="programlisting brush: ini">
[production]

ldap.log_path = /tmp/ldap.log

; Typical options for OpenLDAP
ldap.server1.host = s0.foo.net
ldap.server1.accountDomainName = foo.net
ldap.server1.accountDomainNameShort = FOO
ldap.server1.accountCanonicalForm = 3
ldap.server1.username = &quot;CN=user1,DC=foo,DC=net&quot;
ldap.server1.password = pass1
ldap.server1.baseDn = &quot;OU=Sales,DC=foo,DC=net&quot;
ldap.server1.bindRequiresDn = true

; Typical options for Active Directory
ldap.server2.host = dc1.w.net
ldap.server2.useStartTls = true
ldap.server2.accountDomainName = w.net
ldap.server2.accountDomainNameShort = W
ldap.server2.accountCanonicalForm = 3
ldap.server2.baseDn = &quot;CN=Users,DC=w,DC=net&quot;
</pre>


        <p class="para">
            The above configuration will instruct <span class="classname">Zend_Auth_Adapter_Ldap</span> to
            attempt to authenticate users with the OpenLDAP server <var class="filename">s0.foo.net</var>
            first. If the authentication fails for any reason, the AD server
            <var class="filename">dc1.w.net</var> will be tried.
        </p>

        <p class="para">
            With servers in different domains, this configuration illustrates multi-domain
            authentication. You can also have multiple servers in the same domain to provide
            redundancy.
        </p>

        <p class="para">
            Note that in this case, even though OpenLDAP has no need for the short NetBIOS style
            domain name used by Windows, we provide it here for name canonicalization purposes
            (described in the <em class="emphasis">Username Canonicalization</em> section below).
        </p>
    </div>

    <div class="section" id="zend.auth.adapter.ldap.api"><div class="info"><h1 class="title">The API</h1></div>
        

        <p class="para">
            The <span class="classname">Zend_Auth_Adapter_Ldap</span> constructor accepts three parameters.
        </p>

        <p class="para">
            The <var class="varname">$options</var> parameter is required and must be an array containing
            one or more sets of options. Note that it is <em class="emphasis">an array of arrays</em> of
            <a href="zend.ldap.html" class="link"><span class="classname">Zend_Ldap</span></a> options. Even if you
            will be using only one <acronym class="acronym">LDAP</acronym> server, the options must still be within
            another array.
        </p>

        <p class="para">
            Below is <a href="http://php.net/print_r" class="link external">&raquo;  <span class="methodname">print_r()</span></a>
            output of an example options parameter containing two sets of server options for
            <acronym class="acronym">LDAP</acronym> servers <var class="filename">s0.foo.net</var> and
            <var class="filename">dc1.w.net</var> (the same options as the above <acronym class="acronym">INI</acronym>
            representation):
        </p>

        <pre class="programlisting brush: output">
Array
(
    [server2] =&gt; Array
        (
            [host] =&gt; dc1.w.net
            [useStartTls] =&gt; 1
            [accountDomainName] =&gt; w.net
            [accountDomainNameShort] =&gt; W
            [accountCanonicalForm] =&gt; 3
            [baseDn] =&gt; CN=Users,DC=w,DC=net
        )

    [server1] =&gt; Array
        (
            [host] =&gt; s0.foo.net
            [accountDomainName] =&gt; foo.net
            [accountDomainNameShort] =&gt; FOO
            [accountCanonicalForm] =&gt; 3
            [username] =&gt; CN=user1,DC=foo,DC=net
            [password] =&gt; pass1
            [baseDn] =&gt; OU=Sales,DC=foo,DC=net
            [bindRequiresDn] =&gt; 1
        )

)
</pre>


        <p class="para">
            The information provided in each set of options above is different mainly because AD
            does not require a username be in DN form when binding (see the
            <span class="property">bindRequiresDn</span> option in the <em class="emphasis">Server Options</em>
            section below), which means we can omit a number of options associated with retrieving
            the DN for a username being authenticated.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>What is a Distinguished Name?</b><br /></span>
            

            <p class="para">
                A DN or &quot;distinguished name&quot; is a string that represents the path to an object
                within the <acronym class="acronym">LDAP</acronym> directory. Each comma-separated component is an
                attribute and value representing a node. The components are evaluated in reverse.
                For example, the user account
                <em class="emphasis">CN=Bob Carter,CN=Users,DC=w,DC=net</em> is located directly
                within the <em class="emphasis">CN=Users,DC=w,DC=net container</em>. This structure is
                best explored with an <acronym class="acronym">LDAP</acronym> browser like the
                <acronym class="acronym">ADSI</acronym> Edit <acronym class="acronym">MMC</acronym> snap-in for Active Directory or
                phpLDAPadmin.
            </p>
        </p></blockquote>

        <p class="para">
            The names of servers (e.g. &#039;server1&#039; and &#039;server2&#039; shown above) are largely arbitrary,
            but for the sake of using <span class="classname">Zend_Config</span>, the identifiers should be
            present (as opposed to being numeric indexes) and should not contain any special
            characters used by the associated file formats (e.g. the &#039;<em class="emphasis">.</em>&#039;
            <acronym class="acronym">INI</acronym> property separator, &#039;<em class="emphasis">&amp;</em>&#039; for
            <acronym class="acronym">XML</acronym> entity references, etc).
        </p>

        <p class="para">
            With multiple sets of server options, the adapter can authenticate users in multiple
            domains and provide failover so that if one server is not available, another will be
            queried.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>The Gory Details: What Happens in the Authenticate Method?</b><br /></span>
            

            <p class="para">
                When the  <span class="methodname">authenticate()</span> method is called, the adapter
                iterates over each set of server options, sets them on the internal
                <span class="classname">Zend_Ldap</span> instance, and calls the
                 <span class="methodname">Zend_Ldap::bind()</span> method with the username and password
                being authenticated. The <span class="classname">Zend_Ldap</span> class checks to see if
                the username is qualified with a domain (e.g., has a domain component like
                <var class="filename">alice@foo.net</var> or <var class="filename">FOO\alice</var>). If a domain
                is present, but does not match either of the server&#039;s domain names
                (<var class="filename">foo.net</var> or <acronym class="acronym">FOO</acronym>), a special exception is
                thrown and caught by <span class="classname">Zend_Auth_Adapter_Ldap</span> that causes that
                server to be ignored and the next set of server options is selected. If a domain
                <em class="emphasis">does</em> match, or if the user did not supply a qualified username,
                <span class="classname">Zend_Ldap</span> proceeds to try to bind with the supplied
                credentials. if the bind is not successful, <span class="classname">Zend_Ldap</span> throws
                a <span class="classname">Zend_Ldap_Exception</span> which is caught by
                <span class="classname">Zend_Auth_Adapter_Ldap</span> and the next set of server options is
                tried. If the bind is successful, the iteration stops, and the adapter&#039;s
                 <span class="methodname">authenticate()</span> method returns a successful result. If all
                server options have been tried without success, the authentication fails, and
                 <span class="methodname">authenticate()</span> returns a failure result with error messages
                from the last iteration.
            </p>
        </p></blockquote>

        <p class="para">
            The username and password parameters of the
            <span class="classname">Zend_Auth_Adapter_Ldap</span> constructor represent the credentials
            being authenticated (i.e., the credentials supplied by the user through your
            <acronym class="acronym">HTML</acronym> login form). Alternatively, they may also be set with the
             <span class="methodname">setUsername()</span> and  <span class="methodname">setPassword()</span>
            methods.
        </p>
    </div>

    <div class="section" id="zend.auth.adapter.ldap.server-options"><div class="info"><h1 class="title">Server Options</h1></div>
        

        <p class="para">
            Each set of server options <em class="emphasis">in the context of
            <span class="classname">Zend_Auth_Adapter_Ldap</span></em> consists of the following
            options, which are passed, largely unmodified, to
             <span class="methodname">Zend_Ldap::setOptions()</span>:
        </p>

        <table id="zend.auth.adapter.ldap.server-options.table" class="doctable table"><div class="info"><caption><b>Server Options</b></caption></div>
            

            
                <thead valign="middle">
                    <tr valign="middle">
                        <th>Name</th>
                        <th>Description</th>
                    </tr>

                </thead>


                <tbody valign="middle" class="tbody">
                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">host</span></em></td>

                        <td align="left">
                            The hostname of <acronym class="acronym">LDAP</acronym> server that these options
                            represent. This option is required.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">port</span></em></td>

                        <td align="left">
                            The port on which the <acronym class="acronym">LDAP</acronym> server is listening. If
                            <em class="emphasis">useSsl</em> is <b><tt>TRUE</tt></b>, the default
                            <span class="property">port</span> value is 636. If <span class="property">useSsl</span>
                            is <b><tt>FALSE</tt></b>, the default <span class="property">port</span>
                            value is 389.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">useStartTls</span></em></td>

                        <td align="left">
                            Whether or not the <acronym class="acronym">LDAP</acronym> client should use
                            <acronym class="acronym">TLS</acronym> (aka <acronym class="acronym">SSL</acronym>v2) encrypted
                            transport. A value of <b><tt>TRUE</tt></b> is strongly favored in
                            production environments to prevent passwords from be transmitted in
                            clear text. The default value is <b><tt>FALSE</tt></b>, as servers
                            frequently require that a certificate be installed separately after
                            installation. The <span class="property">useSsl</span> and
                            <span class="property">useStartTls</span> options are mutually exclusive. The
                            <span class="property">useStartTls</span> option should be favored over
                            <span class="property">useSsl</span> but not all servers support this newer
                            mechanism.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">useSsl</span></em></td>

                        <td align="left">
                            Whether or not the <acronym class="acronym">LDAP</acronym> client should use
                            <acronym class="acronym">SSL</acronym> encrypted transport. The
                            <span class="property">useSsl</span> and <span class="property">useStartTls</span>
                            options are mutually exclusive, but <span class="property">useStartTls</span>
                            should be favored if the server and <acronym class="acronym">LDAP</acronym> client
                            library support it. This value also changes the default
                            <span class="property">port</span> value (see <span class="property">port</span>
                            description above).
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">username</span></em></td>

                        <td align="left">
                            The DN of the account used to perform account DN lookups.
                            <acronym class="acronym">LDAP</acronym> servers that require the username to be in DN
                            form when performing the &quot;bind&quot; require this option. Meaning, if
                            <span class="property">bindRequiresDn</span> is <b><tt>TRUE</tt></b>, this
                            option is required. This account does not need to be a privileged
                            account; an account with read-only access to objects under the
                            <span class="property">baseDn</span> is all that is necessary (and preferred
                            based on the <em class="emphasis">Principle of Least Privilege</em>).
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">password</span></em></td>

                        <td align="left">
                            The password of the account used to perform account DN lookups. If this
                            option is not supplied, the <acronym class="acronym">LDAP</acronym> client will attempt
                            an &quot;anonymous bind&quot; when performing account DN lookups.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">bindRequiresDn</span></em></td>

                        <td align="left">
                            Some <acronym class="acronym">LDAP</acronym> servers require that the username used to
                            bind be in DN form like
                            <em class="emphasis">CN=Alice Baker,OU=Sales,DC=foo,DC=net</em> (basically
                            all servers <em class="emphasis">except</em> AD). If this option is
                            <b><tt>TRUE</tt></b>, this instructs
                            <span class="classname">Zend_Ldap</span> to automatically retrieve the DN
                            corresponding to the username being authenticated, if it is not already
                            in DN form, and then re-bind with the proper DN. The default value is
                            <b><tt>FALSE</tt></b>. Currently only Microsoft Active Directory
                            Server (<acronym class="acronym">ADS</acronym>) is known <em class="emphasis">not</em> to
                            require usernames to be in DN form when binding, and therefore this
                            option may be <b><tt>FALSE</tt></b> with AD (and it should be, as
                            retrieving the DN requires an extra round trip to the server).
                            Otherwise, this option must be set to <b><tt>TRUE</tt></b> (e.g.
                            for OpenLDAP). This option also controls the default
                            <span class="property">acountFilterFormat</span> used when searching for
                            accounts. See the <span class="property">accountFilterFormat</span> option.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">baseDn</span></em></td>

                        <td align="left">
                            The DN under which all accounts being authenticated are located. This
                            option is required. if you are uncertain about the correct
                            <span class="property">baseDn</span> value, it should be sufficient to derive it
                            from the user&#039;s <acronym class="acronym">DNS</acronym> domain using
                            <em class="emphasis">DC=</em> components. For example, if the user&#039;s
                            principal name is <var class="filename">alice@foo.net</var>, a
                            <span class="property">baseDn</span> of <em class="emphasis">DC=foo,DC=net</em>
                            should work. A more precise location (e.g.,
                            <em class="emphasis">OU=Sales,DC=foo,DC=net</em>) will be more efficient,
                            however.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">
                            <em class="emphasis"><span class="property">accountCanonicalForm</span></em>
                        </td>

                        <td align="left">
                            A value of 2, 3 or 4 indicating the form to which account names should
                            be canonicalized after successful authentication. Values are as
                            follows: 2 for traditional username style names (e.g.,
                            <em class="emphasis">alice</em>), 3 for backslash-style names (e.g.,
                            <var class="filename">FOO\alice</var>) or 4 for principal style usernames
                            (e.g., <var class="filename">alice@foo.net</var>). The default value is 4
                            (e.g., <var class="filename">alice@foo.net</var>). For example, with a value
                            of 3, the identity returned by
                             <span class="methodname">Zend_Auth_Result::getIdentity()</span> (and
                             <span class="methodname">Zend_Auth::getIdentity()</span>, if
                            <span class="classname">Zend_Auth</span> was used) will always be
                            <var class="filename">FOO\alice</var>, regardless of what form Alice supplied,
                            whether it be <em class="emphasis">alice</em>,
                            <var class="filename">alice@foo.net</var>, <var class="filename">FOO\alice</var>,
                            <var class="filename">FoO\aLicE</var>, <var class="filename">foo.net\alice</var>,
                            etc. See the <em class="emphasis">Account Name Canonicalization</em> section
                            in the <span class="classname">Zend_Ldap</span> documentation for details. Note
                            that when using multiple sets of server options it is recommended, but
                            not required, that the same <span class="property">accountCanonicalForm</span>
                            be used with all server options so that the resulting usernames are
                            always canonicalized to the same form (e.g., if you canonicalize to
                            <var class="filename">EXAMPLE\username</var> with an AD server but to
                            <var class="filename">username@example.com</var> with an OpenLDAP server, that
                            may be awkward for the application&#039;s high-level logic).
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">accountDomainName</span></em></td>

                        <td align="left">
                            The <acronym class="acronym">FQDN</acronym> domain name for which the target
                            <acronym class="acronym">LDAP</acronym> server is an authority (e.g.,
                            <var class="filename">example.com</var>). This option is used to canonicalize
                            names so that the username supplied by the user can be converted as
                            necessary for binding. It is also used to determine if the server is an
                            authority for the supplied username (e.g., if
                            <span class="property">accountDomainName</span> is <var class="filename">foo.net</var>
                            and the user supplies <var class="filename">bob@bar.net</var>, the server will
                            not be queried, and a failure will result). This option is not
                            required, but if it is not supplied, usernames in principal name form
                            (e.g., <var class="filename">alice@foo.net</var>) are not supported. It is
                            strongly recommended that you supply this option, as there are many
                            use-cases that require generating the principal name form.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">
                            <em class="emphasis"><span class="property">accountDomainNameShort</span></em>
                        </td>

                        <td align="left">
                            The &#039;short&#039; domain for which the target <acronym class="acronym">LDAP</acronym> server
                            is an authority (e.g., <acronym class="acronym">FOO</acronym>). Note that there is a
                            1:1 mapping between the <span class="property">accountDomainName</span> and
                            <span class="property">accountDomainNameShort</span>. This option should be used
                            to specify the NetBIOS domain name for Windows networks, but may also
                            be used by non-AD servers (e.g., for consistency when multiple sets of
                            server options with the backslash style
                            <span class="property">accountCanonicalForm</span>). This option is not required
                            but if it is not supplied, usernames in backslash form (e.g.,
                            <var class="filename">FOO\alice</var>) are not supported.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">accountFilterFormat</span></em></td>

                        <td align="left">
                            The <acronym class="acronym">LDAP</acronym> search filter used to search for accounts.
                            This string is a <a href="http://php.net/printf" class="link external">&raquo;  <span class="methodname">printf()</span></a>-style
                            expression that must contain one &#039;<em class="emphasis">%s</em>&#039; to
                            accomodate the username. The default value is
                            &#039;<em class="emphasis">(&amp;(objectClass=user)(sAMAccountName=%s))</em>&#039;,
                            unless <span class="property">bindRequiresDn</span> is set to
                            <b><tt>TRUE</tt></b>, in which case the default is
                            &#039;<em class="emphasis">(&amp;(objectClass=posixAccount)(uid=%s))</em>&#039;. For
                            example, if for some reason you wanted to use
                            <em class="emphasis">bindRequiresDn = true</em> with AD you would need to
                            set <em class="emphasis">accountFilterFormat =
                                &#039;(&amp;(objectClass=user)(sAMAccountName=%s))</em>&#039;.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left"><em class="emphasis"><span class="property">optReferrals</span></em></td>

                        <td align="left">
                            If set to <b><tt>TRUE</tt></b>, this option indicates to the
                            <acronym class="acronym">LDAP</acronym> client that referrals should be followed. The
                            default value is <b><tt>FALSE</tt></b>.
                        </td>
                    </tr>

                </tbody>
            
        </table>


        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                If you enable <em class="emphasis">useStartTls = <b><tt>TRUE</tt></b></em> or
                <em class="emphasis">useSsl = <b><tt>TRUE</tt></b></em> you may find that the
                <acronym class="acronym">LDAP</acronym> client generates an error claiming that it cannot validate
                the server&#039;s certificate. Assuming the <acronym class="acronym">PHP</acronym>
                <acronym class="acronym">LDAP</acronym> extension is ultimately linked to the OpenLDAP client
                libraries, to resolve this issue you can set &quot;<strong class="command">TLS_REQCERT never</strong>&quot;
                in the OpenLDAP client <var class="filename">ldap.conf</var> (and restart the web server)
                to indicate to the OpenLDAP client library that you trust the server. Alternatively,
                if you are concerned that the server could be spoofed, you can export the
                <acronym class="acronym">LDAP</acronym> server&#039;s root certificate and put it on the web server so
                that the OpenLDAP client can validate the server&#039;s identity.
            </p>
        </p></blockquote>
    </div>

    <div class="section" id="zend.auth.adapter.ldap.debugging"><div class="info"><h1 class="title">Collecting Debugging Messages</h1></div>
        

        <p class="para">
            <span class="classname">Zend_Auth_Adapter_Ldap</span> collects debugging information within its
             <span class="methodname">authenticate()</span> method. This information is stored in the
            <span class="classname">Zend_Auth_Result</span> object as messages. The array returned by
             <span class="methodname">Zend_Auth_Result::getMessages()</span> is described as follows
        </p>

        <table id="zend.auth.adapter.ldap.debugging.table" class="doctable table"><div class="info"><caption><b>Debugging Messages</b></caption></div>
            

            
                <thead valign="middle">
                    <tr valign="middle">
                        <th>Messages Array Index</th>
                        <th>Description</th>
                    </tr>

                </thead>


                <tbody valign="middle" class="tbody">
                    <tr valign="middle">
                        <td align="left">Index 0</td>

                        <td align="left">
                            A generic, user-friendly message that is suitable for displaying to
                            users (e.g., &quot;Invalid credentials&quot;). If the authentication is
                            successful, this string is empty.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">Index 1</td>

                        <td align="left">
                            A more detailed error message that is not suitable to be displayed to
                            users but should be logged for the benefit of server operators. If the
                            authentication is successful, this string is empty.
                        </td>
                    </tr>


                    <tr valign="middle">
                        <td align="left">Indexes 2 and higher</td>
                        <td align="left">All log messages in order starting at index 2.</td>
                    </tr>

                </tbody>
            
        </table>


        <p class="para">
            In practice, index 0 should be displayed to the user (e.g., using the FlashMessenger
            helper), index 1 should be logged and, if debugging information is being collected,
            indexes 2 and higher could be logged as well (although the final message always includes
            the string from index 1).
        </p>
    </div>

    <div class="section" id="zend.auth.adapter.ldap.options-common-server-specific"><div class="info"><h1 class="title">Common Options for Specific Servers</h1></div>
        

        <div class="section" id="zend.auth.adapter.ldap.options-common-server-specific.active-directory"><div class="info"><h1 class="title">Options for Active Directory</h1></div>
            

            <p class="para">
                For <acronym class="acronym">ADS</acronym>, the following options are noteworthy:
            </p>

            <table id="zend.auth.adapter.ldap.options-common-server-specific.active-directory.table" class="doctable table"><div class="info"><caption><b>Options for Active Directory</b></caption></div>
                

                
                    <thead valign="middle">
                        <tr valign="middle">
                            <th>Name</th>
                            <th>Additional Notes</th>
                        </tr>

                    </thead>


                    <tbody valign="middle" class="tbody">
                        <tr valign="middle">
                            <td align="left"><em class="emphasis"><span class="property">host</span></em></td>
                            <td align="left">As with all servers, this option is required.</td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><em class="emphasis"><span class="property">useStartTls</span></em></td>

                            <td align="left">
                                For the sake of security, this should be <b><tt>TRUE</tt></b>
                                if the server has the necessary certificate installed.
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><em class="emphasis"><span class="property">useSsl</span></em></td>

                            <td align="left">
                                Possibly used as an alternative to <em class="emphasis">useStartTls</em>
                                (see above).
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><em class="emphasis"><span class="property">baseDn</span></em></td>

                            <td align="left">
                                As with all servers, this option is required. By default AD places
                                all user accounts under the <em class="emphasis">Users</em> container
                                (e.g., <em class="emphasis">CN=Users,DC=foo,DC=net</em>), but the
                                default is not common in larger organizations. Ask your AD
                                administrator what the best DN for accounts for your application
                                would be.
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left">
                                <em class="emphasis"><span class="property">accountCanonicalForm</span></em>
                            </td>

                            <td align="left">
                                You almost certainly want this to be 3 for backslash style names
                                (e.g., <var class="filename">FOO\alice</var>), which are most familiar to
                                Windows users. You should <em class="emphasis">not</em> use the
                                unqualified form 2 (e.g., <em class="emphasis">alice</em>), as this may
                                grant access to your application to users with the same username in
                                other trusted domains (e.g., <var class="filename">BAR\alice</var> and
                                <var class="filename">FOO\alice</var> will be treated as the same user).
                                (See also note below.)
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left">
                                <em class="emphasis"><span class="property">accountDomainName</span></em>
                            </td>

                            <td align="left">
                                This is required with AD unless
                                <span class="property">accountCanonicalForm</span> 2 is used, which, again,
                                is discouraged.
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left">
                                <em class="emphasis"><span class="property">accountDomainNameShort</span></em>
                            </td>

                            <td align="left">
                                The NetBIOS name of the domain that users are in and for which the
                                AD server is an authority. This is required if the backslash style
                                <span class="property">accountCanonicalForm</span> is used.
                            </td>
                        </tr>

                    </tbody>
                
            </table>


            <blockquote class="note"><p><b class="note">Note</b>: 
                <p class="para">
                    Technically there should be no danger of accidental cross-domain authentication
                    with the current <span class="classname">Zend_Auth_Adapter_Ldap</span> implementation,
                    since server domains are explicitly checked, but this may not be true of a
                    future implementation that discovers the domain at runtime, or if an alternative
                    adapter is used (e.g., Kerberos). In general, account name ambiguity is known to
                    be the source of security issues, so always try to use qualified account names.
                </p>
            </p></blockquote>
        </div>

        <div class="section" id="zend.auth.adapter.ldap.options-common-server-specific.openldap"><div class="info"><h1 class="title">Options for OpenLDAP</h1></div>
            

            <p class="para">
                For OpenLDAP or a generic <acronym class="acronym">LDAP</acronym> server using a typical
                posixAccount style schema, the following options are noteworthy:
            </p>

            <table id="zend.auth.adapter.ldap.options-common-server-specific.openldap.table" class="doctable table"><div class="info"><caption><b>Options for OpenLDAP</b></caption></div>
                

                
                    <thead valign="middle">
                        <tr valign="middle">
                            <th>Name</th>
                            <th>Additional Notes</th>
                        </tr>

                    </thead>


                    <tbody valign="middle" class="tbody">
                        <tr valign="middle">
                            <td align="left"><em class="emphasis"><span class="property">host</span></em></td>
                            <td align="left">As with all servers, this option is required.</td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><em class="emphasis"><span class="property">useStartTls</span></em></td>

                            <td align="left">
                                For the sake of security, this should be <b><tt>TRUE</tt></b>
                                if the server has the necessary certificate installed.
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><em class="emphasis"><span class="property">useSsl</span></em></td>

                            <td align="left">
                                Possibly used as an alternative to <span class="property">useStartTls</span>
                                (see above).
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><em class="emphasis"><span class="property">username</span></em></td>

                            <td align="left">
                                Required and must be a DN, as OpenLDAP requires that usernames be
                                in DN form when performing a bind. Try to use an unprivileged
                                account.
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><em class="emphasis"><span class="property">password</span></em></td>

                            <td align="left">
                                The password corresponding to the username above, but this may be
                                omitted if the <acronym class="acronym">LDAP</acronym> server permits an anonymous
                                binding to query user accounts.
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><em class="emphasis"><span class="property">bindRequiresDn</span></em></td>

                            <td align="left">
                                Required and must be <b><tt>TRUE</tt></b>, as OpenLDAP
                                requires that usernames be in DN form when performing a bind.
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left"><em class="emphasis"><span class="property">baseDn</span></em></td>

                            <td align="left">
                                As with all servers, this option is required and indicates the DN
                                under which all accounts being authenticated are located.
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left">
                                <em class="emphasis"><span class="property">accountCanonicalForm</span></em>
                            </td>

                            <td align="left">
                                Optional, but the default value is 4 (principal style names like
                                <var class="filename">alice@foo.net</var>), which may not be ideal if your
                                users are used to backslash style names (e.g.,
                                <var class="filename">FOO\alice</var>). For backslash style names use
                                value 3.
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left">
                                <em class="emphasis"><span class="property">accountDomainName</span></em>
                            </td>

                            <td align="left">
                                Required unless you&#039;re using
                                <span class="property">accountCanonicalForm</span> 2, which is not
                                recommended.
                            </td>
                        </tr>


                        <tr valign="middle">
                            <td align="left">
                                <em class="emphasis"><span class="property">accountDomainNameShort</span></em>
                            </td>

                            <td align="left">
                                If AD is not also being used, this value is not required.
                                Otherwise, if <span class="property">accountCanonicalForm</span> 3 is used,
                                this option is required and should be a short name that corresponds
                                adequately to the <span class="property">accountDomainName</span> (e.g., if
                                your <span class="property">accountDomainName</span> is
                                <var class="filename">foo.net</var>, a good
                                <span class="property">accountDomainNameShort</span> value might be
                                <acronym class="acronym">FOO</acronym>).
                            </td>
                        </tr>

                    </tbody>
                
            </table>

        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.auth.adapter.http.html">HTTP Authentication Adapter</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.auth.html">Zend_Auth</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.auth.adapter.openid.html">Open ID Authentication</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="reference.html">Refer&ecirc;ncia do Zend Framework</a></li>
  <li class="header up"><a href="zend.auth.html">Zend_Auth</a></li>
  <li><a href="zend.auth.introduction.html">Introduction</a></li>
  <li><a href="zend.auth.adapter.dbtable.html">Database Table Authentication</a></li>
  <li><a href="zend.auth.adapter.digest.html">Digest Authentication</a></li>
  <li><a href="zend.auth.adapter.http.html">HTTP Authentication Adapter</a></li>
  <li class="active"><a href="zend.auth.adapter.ldap.html">LDAP Authentication</a></li>
  <li><a href="zend.auth.adapter.openid.html">Open ID Authentication</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>